<?php
/**
 * interfaces for webappkit.db.link
 *
 * @link http://webappkit.net
 * @package webappkit
 * @subpackage db
 * @author J.Ducastel <nospam0@ducastel.name>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */

interface iDbLink {
    /**
     * Tries to connect to database using preset configuration
     * opens link, select db if defined, set encoding if defined
     * @return bool
     */
    public function _connect();

    /**
     * selects database
     * @param string $db database name
     * @return bool
     */
    public function selectDb($db);

    /**
     * gets a select result object
     * @param string $sql SQL query
     * @return DbResult
     */
    public function getResult($sql);

    /**
     * sets connection encoding
     * @param string $encoding
     * @return bool
     */
    public function setEncoding($encoding);
}

interface iDbResult {

    /**
     * fetch a line as associative array.
     * @access public
     * @return array
     */
    public function fetchAssoc();

    /**
     * fetch a line as CSV string
     * @return string
     */
    public function fetchCsv();

    /**
     * return lines count
     * if not buffered and lines remain, would be incorrect
     * @access public
     * @return int
     */
    public function count();

    /**
     * get pages count having $lines lines per page, skip to page $page
     * @access public
     * @param int $lines lines per page
     * @param int $page go to page
     * @return int pages count
     */
    // public function paginate($lines, $page=1);

    /**
     * get back SQL query
     * @return string SQL query
     */
    public function getSql();

    /**
     * @return string sql error if occured
     */
    public function getError();

    /**
     * tells if query failed
     * @return bool
     */
    function failed();

    /**
     * force download as a CSV file
     * wont send anything if result is empty
     * @return int lines sent
     */
    function downloadAsCsv($filename, $separator=';', $enclosure='"');
}
